/**
 * 文件：MatchingService.java
 * 作者：赵子樵
 * 完成度：完成
 * 最后修改日期：2023-7-9 02:00
 */

package com.gomokult.service;

import com.gomokult.entity.MatchingRequest;

/**
 * 提供与对局匹配相关的服务接口。<p>
 * * 由于该服务的细节方面不易表述，由本人负责实现。
 * @author 赵子樵
 */
public interface MatchingService {
	/**
	 * 发起一个段位等级为{@code level}的匹配请求{@code request}。
	 * @param request 封装了请求的基本信息，包括发起匹配请求的用户ID以及请求时刻的时间戳
	 * @param level 该请求的请求等级，用于记录用户的段位信息
	 */
	void requestMatching(MatchingRequest request, int level);
	
	/**
	 * 清除用户{@code userID}发起的匹配请求。
	 * @param userID 目标用户ID
	 */
	void clearRequest(int userID);
	
	/**
	 * 取消用户{@code userID}发起的匹配请求。
	 * @param userID 目标用户ID
	 */
	void cancelMatching(int userID);
	
	/**
	 * 获取用户{@code userID}的匹配结果。若匹配成功，该方法返回匹配到的对手ID；若匹配失败或被取消，返回{@code -1}；若请求未完成或进行中，返回{@code 0}。
	 * @param userID 目标用户ID
	 * @return 一个格式化的字符串。字符串中包含两个tokens，使用{@code '#'}分隔。第一个token表示发起请求的用户分配到的棋子颜色，分别使用{@code "B"}与{@code "W"}表示；第二个token是一个整数，表示匹配到的用户ID
	 */
	String pollMatchingResult(int userID);
}
